### Rozdział 45. Dokumentacja – instrukcja obsługi Twojej strony dziś i „mapa skarbów” na jutro

Dobra dokumentacja to coś więcej niż notatki do projektu. To instrukcja obsługi dla właściciela, ściąga dla przyszłego wykonawcy i pamięć zbiorowa całego zespołu. Gdy strona działa, wszystko wydaje się oczywiste. Wystarczy jednak, że minie kilka miesięcy, zmieni się osoba odpowiedzialna albo pojawi się potrzeba rozbudowy – i nagle brakuje odpowiedzi: co, gdzie, jak zostało zrobione. Wtedy traci się czas na odkrywanie tego, co można było zapisać w 15 minut.

W tym rozdziale pokazuję, jak przygotować pełną dokumentację użytkownika i techniczną dla witryny opartej na WordPressie (i nie tylko). Zadbamy o dwa poziomy: codzienną pracę (tworzenie treści, wtyczki, aktualizacje, SEO, bezpieczeństwo) oraz warstwę „pod maską” (architektura, motyw, blokowy builder, pola niestandardowe, integracje, środowiska, deploy). Dzięki temu właściciel będzie działał pewnie na co dzień, a każdy specjalista – Ty dziś lub ktoś inny jutro – szybko zrozumie, co i jak rozwijać bez ryzyka.

#### Po co Ci dokumentacja i dla kogo ją piszesz
- Dla użytkownika (właściciela/redaktora): żeby mógł samodzielnie publikować, edytować, aktualizować i dbać o podstawy bezpieczeństwa bez proszenia o pomoc na każdą drobnostkę.
- Dla wykonawcy/rozwojowca: żeby rozumiał architekturę, zależności i procesy wdrożeniowe. To skraca czas rozbudowy i zmniejsza ryzyko regresów.
- Dla biznesu: żeby nie uzależniać się od jednej osoby. Wiedza jest w dokumencie, nie tylko „w głowie”.

Dobra dokumentacja jest żywa: aktualizowana przy ważniejszych zmianach, łatwa do odnalezienia, pisana prostym językiem.

#### Jak przechowywać i udostępniać dokumentację
- Jedno miejsce „źródła prawdy”: Notion/Confluence/Google Docs z logiczną nawigacją (spis treści, wyszukiwarka).
- Wersjonowanie: daty aktualizacji na górze, krótkie logi zmian („v1.3 – dodano sekcję o nowym builderze”).
- Dostępy: właściciel, redaktorzy (tylko część użytkowa), wykonawcy (całość). Hasła i klucze – w menedżerze haseł, nie w dokumencie.
- Załączniki: zrzuty ekranu, krótkie gify/wideo 2–3 min, eksporty ustawień (np. z wtyczek SEO/backup).

Konsekwencja w przechowywaniu to połowa sukcesu – nawet najlepsza wiedza bezużyteczna, jeśli nie wiadomo, gdzie jest.

---

## Część I. Dokumentacja użytkownika (operacyjna)

To rozdział dla osoby, która prowadzi stronę na co dzień. Pisany prostym, konkretnym językiem, z krokami i zrzutami.

### 1) Z czego składa się Twoja strona
- Strony stałe: Strona główna, Oferta/Usługi, O mnie, Kontakt, Polityki (Prywatność, Cookies).
- Blog: wpisy, kategorie (lista i opis), tagi (główne etykiety – nie tworzymy nowych „na wszystko”).
- Elementy wspólne: nagłówek (menu), stopka (linki, dane), sidebar (jeśli używany).
- Formularze: kontakt, zapis na newsletter, lead magnet – gdzie je znaleźć i jak edytować treść potwierdzeń.
- Media: biblioteka (obrazy, PDF, wideo), zasady nazewnictwa i wagi plików.

Cel: użytkownik rozumie mapę witryny i wie, gdzie „dotykać”, a gdzie lepiej nie.

### 2) Tworzenie i edycja treści (WordPress)
- Nowy wpis: tytuł, lead (pierwszy akapit), nagłówki H2/H3, akapity, listy, cytaty, wstawianie obrazów z alt‑tekstem, osadzanie wideo.
- Kategorie i tagi: kiedy tworzyć nową kategorię (rzadko), jak trzymać porządek (max 5–8 kategorii), jak tagować stałą listą etykiet.
- SEO on‑page: ustawienie tytułu i opisu meta (Yoast/AIOSEO), skracanie adresu URL, podgląd w wyszukiwarce.
- Linkowanie wewnętrzne: 3–5 linków do powiązanych treści i kluczowych stron (Oferta, Kontakt).
- Checklista publikacji: podgląd na desktopie i mobile, korekta, SEO, publikacja, dystrybucja (newsletter, social).

Warto dodać krótkie filmy z ekranu (2–3 min) do powtarzalnych czynności.

### 3) Zarządzanie mediami (obrazy i pliki)
- Nazwy plików: proste, opisowe, bez polskich znaków i spacji (myślniki).
- Waga i format: zdjęcia do wpisów 60–120 KB, hero 150–250 KB, format WebP/AVIF; PDF kompresowany.
- Alt‑tekst: opis co na obrazku i po co w kontekście wpisu (wspiera dostępność i SEO).
- Porządek: nie duplikuj, używaj wyszukiwarki w bibliotece, nadawaj sensowne tytuły.

To najczęstsze źródło „puchnięcia” strony – zapobieganie jest łatwiejsze niż odchudzanie.

### 4) Wtyczki – co jest zainstalowane i do czego służy
- SEO (np. Yoast/AIOSEO): tytuły, opisy, mapa witryny, indeksowanie.
- Cache i wydajność (np. WP Super Cache/WP Rocket): oczyszczanie cache po zmianach, ostrożność przy przełącznikach.
- Bezpieczeństwo (np. Wordfence/Sucuri): skan, zapora, alerty.
- Formularze (np. Contact Form 7/WPForms): pola, odbiorcy, wiadomości potwierdzające.
- Kopie zapasowe (np. UpdraftPlus): harmonogram, lokalizacja, przywracanie.
- Inne krytyczne: builder (Elementor/Gutenberg rozszerzenia), galerie, tłumaczenia (jeśli są).

Przy każdej wtyczce: „kiedy używać”, „czego nie zmieniać”, „gdzie jest konfiguracja”.

### 5) Aktualizacje i bezpieczeństwo – bezpieczny rytuał
- Kolejność: backup → wtyczki → motyw → WordPress (core). Po każdej grupie – szybki test (strona główna, formularz, edytor).
- Backup: jak zrobić ręcznie, gdzie się zapisuje, jak przywrócić. Raz na tydzień automatycznie + przed większymi zmianami.
- Użytkownicy: role (Administrator/Redaktor), silne hasła, 2FA, odpinanie starych dostępów.
- Rozpoznawanie problemów: co robić przy białym ekranie, błędach 500, podejrzanych przekierowaniach.

To część, która oszczędza najwięcej nerwów.

### 6) SEO i treści – codzienne minimum
- Każdy wpis: tytuł, opis, nagłówki, alt‑teksty, linki wewnętrzne, linki „co dalej”.
- Mapa witryny i indeksacja: gdzie sprawdzić, czy wpis się dodał; Search Console – podstawowe raporty (indeksacja, pokrycie).
- Aktualizacje artykułów: dodawanie nowości i linków co 3–6 miesięcy.

SEO to higiena – nie jednorazowe działanie.

### 7) E‑mail i formularze – co się dzieje po wysyłce
- Gdzie trafiają zgłoszenia (poczta, CRM/ESP), jak sprawdzić logi formularzy (jeśli wtyczka wspiera), jak wysłać „resend”.
- E‑mail powitalny i strona „Dziękuję”: spójność komunikatów, gdzie to edytować.
- Najczęstsze problemy z dostarczalnością: SPF/DKIM (w skrócie, do kogo pisać), folder Oferty/Spam.

---

## Część II. Dokumentacja techniczna (dla rozwoju i utrzymania)

To rozdział „pod maską”: dla Ciebie i każdego specjalisty, który kiedyś dołączy.

### 1) Architektura projektu
- Hosting i środowiska: dostawca, parametry (PHP, baza), staging/production, sposób deployu (ręcznie/CI/CD, SFTP/Git).
- Domeny i DNS: rejestrator, rekordy A/AAAA/CNAME, poczta (SPF/DKIM/DMARC), subdomeny (np. staging).
- Certyfikaty SSL: gdzie zarządzane (Let’s Encrypt/Cloudflare), auto‑odnowienia.

Na jednej stronie opisz „jak to jest zbudowane i gdzie sięgać”.

### 2) Motyw i front‑end
- Motyw bazowy: nazwa, wersja, czy child theme (gdzie), konwencje (SCSS/CSS, katalogi, preprocesory).
- Builder (jeśli użyty): Elementor/Gutenberg (ACF Blocks)/WPBakery – lista szablonów, globalne style, biblioteka bloków.
- Dane dynamiczne: ACF/Custom Post Types – lista pól i ich znaczenie (np. „hero_title”, „testimonial_list”), gdzie są mapowane w szablonach.
- Snippety i functions.php: spis własnych funkcji, hooków, filtrów (np. modyfikacja breadcrumbs, czyszczenie head).
- Pliki krytyczne: style, skrypty, kolejności ładowania, zależności.

To skraca czas orientacji nowej osobie z dni do godzin.

### 3) Wtyczki – lista kontrolowana i konfiguracje
- Lista aktywnych wtyczek z rolami („krytyczna/ważna/dodatkowa”), wersje, link do dokumentacji zewnętrznej.
- Konfiguracje eksportowalne: SEO (eksport ustawień), cache (profile), bezpieczeństwo (zasady), formularze (eksport form).
- Polityka aktualizacji: które wtyczki aktualizujemy ręcznie (bo wrażliwe), które automatycznie.

Przy krytycznych wtyczkach dopisz „checklistę po aktualizacji”.

### 4) Integracje i klucze
- ESP/CRM (Mailerlite/Mailchimp/HubSpot): gdzie są klucze API, jakie listy/grupy, tagowanie leadów, scenariusze automatyzacji (welcomer, lead magnet).
- Płatności (jeśli e‑commerce): bramki (Stripe/PayU/Przelewy24), webhooki, mapowanie statusów zamówień.
- Analityka i piksele: Google Tag Manager (ID, kontener), GA4 (ID), Meta Pixel, inne – lista eventów i naming convention.
- Zewnętrzne usługi: CDN, reCAPTCHA, mapy, wyszukiwarka (np. Algolia) – gdzie skonfigurowane, gdzie zmieniać klucze.

Klucze trzymaj w menedżerze haseł; w dokumentacji – tylko lokalizacja i właściciel.

### 5) E‑commerce (jeśli dotyczy)
- Typ sklepu (WooCommerce/EDD), ustawienia podatków, wysyłek, e‑maili transakcyjnych.
- Szablony nadpisane w motywie (np. single-product.php), hooki i filtry.
- Kupony, programy rabatowe, zasady koszyka i checkoutu (dodatkowe pola?).

To miejsca, które najczęściej pękają po aktualizacjach – miej je spisane.

### 6) Deploy i kopie zapasowe
- Proces deployu: jak przygotować zmiany (staging), testy (lista ścieżek), okno wdrożenia, rollback (jak wrócić w 5 minut).
- Backupy: harmonogram (automaty), lokalizacje (S3/Dropbox/serwer), test przywrócenia (kiedy ostatnio robiony).
- Logowanie błędów: gdzie szukać (WP_DEBUG_LOG, logi serwera, Sentry JS), jak zgłaszać.

Jedna strona „co zrobić, gdy coś padnie” – bezcenne w stresie.

### 7) Standardy kodowania i dostępności
- PHP/JS/CSS: standardy (PSR‑12, ESLint/Prettier, Stylelint), konwencje nazewnictwa (BEM).
- Dostępność: kontrasty, focus states, aria‑label, kolejność nagłówków. Minimalny audyt (axe/Lighthouse) po większych zmianach.
- Wydajność: polityka obrazów (WebP/AVIF, srcset), lazy‑load, minimalizacja, eliminacja render‑blocking, CWV cele (zielone metryki dla kluczowych stron).

To „reguły gry”, które utrzymują jakość.

### 8) Rejestr zmian (changelog)
- Wersja, data, zakres (funkcje, poprawki, aktualizacje), wpływ na użytkownika, instrukcja testów po wdrożeniu.
- Linki do PR/zgłoszeń, jeśli używacie repozytorium.

W razie problemów wiesz, „co mogło to zepsuć”.

---

## Część III. Procedury, checklisty i materiały „na jutro”

To gotowe, krótkie instrukcje, do których wraca się najczęściej.

- Publikacja wpisu – checklista (1 strona).
- Aktualizacja i testy poaktualizacyjne – checklista.
- Przywrócenie z backupu – checklista.
- Dodanie nowej kategorii/pozycji w menu – checklista.
- Wdrożenie zmian na produkcję – checklista (z oknem czasowym i listą kontrolną).
- „Co zrobić, gdy…” – mini procedury:
  - …formularz nie wysyła maili (kroki diagnostyczne).
  - …strona zwalnia (sprawdź obrazy, cache, raporty PSI).
  - …podejrzewasz infekcję (zablokuj loginy, skan, przywróć, kontakt do wsparcia).

Dodaj krótkie wideo/gify do najczęstszych procesów. Ruchomy obraz uczy szybciej.

---

## Część IV. Jak utrzymywać dokumentację w ruchu

- Odpowiedzialny: jedna osoba (Ty lub ktoś po stronie klienta) jest „właścicielem” dokumentacji.
- Reguła aktualizacji: każda większa zmiana = 10 minut na uzupełnienie dokumentu (szczególnie: nowe wtyczki, zmiany w procesie deployu, integracje).
- Przegląd kwartalny: czy sekcje są aktualne, czy zewnętrzne linki żyją, czy checklisty odzwierciedlają realny proces.
- Widoczność: link do dokumentacji w stopce kokpitu WP (np. widget w „Kokpit”), żeby każdy redaktor miał ją pod ręką.

Dokument, do którego się nie wraca, umiera. Zadbaj, by żył.

---

## Dodatkowe rekomendacje biznesowe

- Przekaż dokumentację klientowi jako element odbioru projektu (wartość dodana).
- Zaproponuj pakiet opieki (maintenance) i rozwoju treści z odniesieniem do dokumentacji: „opieramy się na tych procedurach, raportujemy zmiany do tej sekcji”.
- Ustal SLA i zasady kontaktu (kanał, czas reakcji) – zapisz w dokumencie „Kontakt i wsparcie”.

To porządkuje współpracę i oszczędza czas obu stron.

### Podsumowanie rozdziału

Dokumentacja to inwestycja, która zwraca się za każdym razem, gdy trzeba coś poprawić, rozwinąć albo naprawić. Daje właścicielowi pewność w codziennej pracy (wpisy, obrazy, aktualizacje, SEO), a wykonawcy – jasny obraz architektury, motywu, wtyczek, integracji i procesu wdrożeń. W jednym miejscu trzymasz mapę treści, instrukcje użytkowe, opis kodu i procedury „na awarie”. Dzięki temu projekt nie jest „czarną skrzynką”, tylko przejrzystym narzędziem, które można rozwijać spokojnie i bezpiecznie – przez Ciebie dziś i przez kogokolwiek jutro.